home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / share / catman / p_man / cat3dm / audio / alWriteBuffers.z / alWriteBuffers
Encoding:
Text File  |  1998-10-20  |  13.5 KB  |  331 lines

  1.  
  2.  
  3.  
  4. aaaallllWWWWrrrriiiitttteeeeBBBBuuuuffffffffeeeerrrrssss((((3333ddddmmmm))))                                        aaaallllWWWWrrrriiiitttteeeeBBBBuuuuffffffffeeeerrrrssss((((3333ddddmmmm))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      alWriteBuffers - write flexibly interleaved or non-interleaved audio data
  10.      to an audio port
  11.  
  12. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  13.      ####iiiinnnncccclllluuuuddddeeee <<<<ddddmmmmeeeeddddiiiiaaaa////aaaauuuuddddiiiioooo....hhhh>>>>
  14.  
  15.      iiiinnnntttt aaaallllWWWWrrrriiiitttteeeeBBBBuuuuffffffffeeeerrrrssss((((ccccoooonnnnsssstttt AAAALLLLppppoooorrrrtttt ppppoooorrrrtttt,,,, vvvvooooiiiidddd ********bbbbuuuuffffssss,,,, iiiinnnntttt ****ssssttttrrrriiiiddddeeeessss,,,, ccccoooonnnnsssstttt iiiinnnntttt ffffrrrraaaammmmeeeeccccoooouuuunnnntttt))))
  16.  
  17. PPPPAAAARRRRAAAAMMMMEEEETTTTEEEERRRR
  18.      _p_o_r_t         is the audio output port to which you want to write samples.
  19.                   This is the returned value of an aaaallllOOOOppppeeeennnnPPPPoooorrrrtttt((((3333ddddmmmm)))) call.
  20.  
  21.      _b_u_f_s         is an array of pointers to sample buffers, each element of
  22.                   which corresponds to a single channel of audio output.
  23.  
  24.      _s_t_r_i_d_e_s      is an array of integers, one corresponding to each output
  25.                   channel. Each element indicates the number of interleaved
  26.                   channels in the buffer directed at that channel.
  27.  
  28.      _f_r_a_m_e_c_o_u_n_t   is the number of sample frames that you want to write to the
  29.                   audio port.
  30.  
  31. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  32.      aaaallllWWWWrrrriiiitttteeeeBBBBuuuuffffffffeeeerrrrssss transfers data to an audio port from a set of buffers, or
  33.      from different locations in a single buffer. aaaallllWWWWrrrriiiitttteeeeBBBBuuuuffffffffeeeerrrrssss allows the
  34.      application to specify how the data is interleaved.
  35.  
  36.      _b_u_f_s is an array of pointers to sample buffers. Each element of _b_u_f_s
  37.      corresponds to one output channel. If the element is 0, that channel will
  38.      be zeroed on output. This allows an application to only direct audio at
  39.      the channels of interest.
  40.  
  41.      The sample buffers can be arbitrarily interleaved; the _s_t_r_i_d_e_s parameter
  42.      indicates the number of channels in each source sample buffer. For
  43.      example, if _s_t_r_i_d_e_s[_n] is 1, then bufs[n] is mono; if _s_t_r_i_d_e_s[_n] is 2,
  44.      then bufs[n] is interleaved stereo, and aaaallllWWWWrrrriiiitttteeeeFFFFrrrraaaammmmeeeessss will read every
  45.      other sample from that buffer.  The elements of _s_t_r_i_d_e_s can have any
  46.      value. If _s_t_r_i_d_e_s is 0, all the sample buffers are considered mono, and
  47.      aaaallllWWWWrrrriiiitttteeeeBBBBuuuuffffffffeeeerrrrssss does non-interleaved output.
  48.  
  49.      There must be exactly as many elements in _b_u_f_s and _s_t_r_i_d_e_s as the number
  50.      of channels specified for the port with aaaallllSSSSeeeettttCCCChhhhaaaannnnnnnneeeellllssss((((3333ddddmmmm)))).
  51.  
  52.      aaaallllWWWWrrrriiiitttteeeeBBBBuuuuffffffffeeeerrrrssss blocks until _f_r_a_m_e_c_o_u_n_t sample frames have been written to
  53.      the port.  If you do not wish to block, make sure that _f_r_a_m_e_c_o_u_n_t is less
  54.      than the return value of aaaallllGGGGeeeettttFFFFiiiillllllllaaaabbbblllleeee((((3333ddddmmmm)))).
  55.  
  56.      The expected format of each sample depends upon the configuration of the
  57.      audio port. Each sample can be an 8-, 16-, or 32-bit integer, or a
  58.      single- or double-precision floating-point value or subcode data; see
  59.      aaaallllSSSSeeeettttSSSSaaaammmmppppFFFFmmmmtttt((((3333ddddmmmm)))) and aaaallllSSSSeeeettttWWWWiiiiddddtttthhhh((((3333ddddmmmm)))) for a description of how these
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. aaaallllWWWWrrrriiiitttteeeeBBBBuuuuffffffffeeeerrrrssss((((3333ddddmmmm))))                                        aaaallllWWWWrrrriiiitttteeeeBBBBuuuuffffffffeeeerrrrssss((((3333ddddmmmm))))
  71.  
  72.  
  73.  
  74.      formats work. By default, the sample format is 16-bit integer (short).
  75.  
  76.      Note that since an audio port contains an internal queue, samples written
  77.      to the port will not immediately come out the associated audio device or
  78.      devices. For precise synchronization of audio and other media, use
  79.      aaaallllGGGGeeeettttFFFFrrrraaaammmmeeeeTTTTiiiimmmmeeee((((3333ddddmmmm)))) and aaaallllGGGGeeeettttFFFFrrrraaaammmmeeeeNNNNuuuummmmbbbbeeeerrrr((((3333ddddmmmm)))) to determine when samples
  80.      will actually be output.
  81.  
  82.      In order to achieve the best possible performance, aaaallllWWWWrrrriiiitttteeeeBBBBuuuuffffffffeeeerrrrssss does
  83.      not attempt to verify that _p_o_r_t, _b_u_f_s, or _s_t_r_i_d_e_s are valid. You should
  84.      make certain these values are valid before passing them as arguments to
  85.      aaaallllWWWWrrrriiiitttteeeeBBBBuuuuffffffffeeeerrrrssss.
  86.  
  87. EEEEXXXXAAAAMMMMPPPPLLLLEEEESSSS
  88.      The following code fragment opens an 8-channel audio output port and
  89.      writes 8 separate mono buffers to it. Then it mutes channels 3 and 5 and
  90.      writes the same data.
  91.  
  92.           ALport p;
  93.           short buf[8][1000];
  94.           void *bufs[8];
  95.           int i,j;
  96.           ALconfig c;
  97.  
  98.           c = alNewConfig();
  99.           if (!c) {
  100.               printf("config create failed:%s\n", alGetErrorString(oserror()));
  101.               exit(-1);
  102.           }
  103.  
  104.           alSetChannels(c, 8);
  105.  
  106.           /* open a port with our configuration */
  107.           p = alOpenPort("alWriteBuffers example","w",c);
  108.  
  109.           if (!p) {
  110.               printf("port open failed:%s\n", alGetErrorString(oserror()));
  111.               exit(-1);
  112.           }
  113.  
  114.           /*
  115.            * Fill our buffer. This isn't real audio data here; it's DC on each
  116.            * channel. In a real application, we'd want more meaningful data in
  117.            * each of the buffers.
  118.            */
  119.           for (i = 0; i < 8; i++) {
  120.                /* fill channel i */
  121.                   for (j = 0; j < 1000; j++) {
  122.                           buf[i][j] = i * 2000;
  123.                   }
  124.                   bufs[i] = buf[i];
  125.           }
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. aaaallllWWWWrrrriiiitttteeeeBBBBuuuuffffffffeeeerrrrssss((((3333ddddmmmm))))                                        aaaallllWWWWrrrriiiitttteeeeBBBBuuuuffffffffeeeerrrrssss((((3333ddddmmmm))))
  137.  
  138.  
  139.  
  140.           alWriteBuffers(p, bufs, 0, 1000);          /* write 1000 8-channel frames */
  141.  
  142.           /*
  143.            * Now mute channels 3 and 5
  144.            */
  145.           bufs[2] = 0;   /* channel 3 */
  146.           bufs[4] = 0;   /* channel 5 */
  147.  
  148.           alWriteBuffers(p, bufs, 0, 1000);          /* write 1000 8-channel frames */
  149.           }
  150.  
  151.  
  152.      The following example writes a single 16-channel buffer to 2 8-channel
  153.      devices. This is somewhat simplified, since it does not actually
  154.      synchronize the audio between the devices. For examples of how to do
  155.      that, see the example "scrub" in /usr/share/src/dmedia/audio.
  156.  
  157.           #include <audio.h>
  158.  
  159.           #define NPORTS 2
  160.           #define NCHANS_PER_PORT 8
  161.           #define BUF_NCHANS (NPORTS*NCHANS_PER_PORT)
  162.  
  163.           main()
  164.           {
  165.               ALport p[NPORTS];
  166.               float buf[1000 * BUF_NCHANS];
  167.               void *bufs[NPORTS][NCHANS_PER_PORT];
  168.               int strides[NCHANS_PER_PORT];
  169.               ALconfig c;
  170.               int i, j, k = 0;
  171.  
  172.               /*
  173.                * Set up an array of device resource ID's. To do multi-device
  174.                * I/O meaningfully,  we'd want these to be different resource ID's.
  175.                * This here will open 2 ports to the same resource ID, and the
  176.                * audio system will mix the 2 ports.
  177.                */
  178.               int device[NPORTS]={AL_DEFAULT_OUTPUT, AL_DEFAULT_OUTPUT};
  179.  
  180.               for (i = 0; i < 16000; i++) {
  181.                buf[i] = (i & 15) * 1000.0;
  182.               }
  183.  
  184.               c = alNewConfig();
  185.               if (!c) {
  186.                printf("config create failed:%s\n", alGetErrorString(oserror()));
  187.                exit(-1);
  188.               }
  189.  
  190.               alSetChannels(c, NCHANS_PER_PORT);
  191.               alSetFloatMax(c, 32767);
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. aaaallllWWWWrrrriiiitttteeeeBBBBuuuuffffffffeeeerrrrssss((((3333ddddmmmm))))                                        aaaallllWWWWrrrriiiitttteeeeBBBBuuuuffffffffeeeerrrrssss((((3333ddddmmmm))))
  203.  
  204.  
  205.  
  206.               alSetSampFmt(c, AL_SAMPFMT_FLOAT);
  207.  
  208.               /*
  209.                * Let's assume that in this case we know our floating-point data
  210.                * to be in range. We turn limiting off for (potentially) increased
  211.                * performance.
  212.                */
  213.               alSetLimiting(c, 0);
  214.  
  215.               /*
  216.                * Set up bufs & strides to make different NCHANS-channel "windows"
  217.                * into our buffer.
  218.                */
  219.               k = 0;
  220.               for (j=0; j < NPORTS; j++) {
  221.                for (i=0; i < NCHANS_PER_PORT; i++) {
  222.                    bufs[j][i] = &buf[k++];
  223.                }
  224.               }
  225.               for (i=0; i < NCHANS_PER_PORT; i++) {
  226.                strides[i] = BUF_NCHANS; /* 16, by default */
  227.               }
  228.  
  229.               /*
  230.                * Open up NPORTS audio ports. Note that we aren't doing
  231.                * anything special to synchronize the ports here; they won't
  232.                * in general be sync'ed.
  233.                */
  234.               for (i = 0; i < NPORTS; i++) {
  235.                alSetDevice(c, device[i]);
  236.  
  237.                p[i] = alOpenPort("alWriteBuffers example","w",c);
  238.  
  239.                if (!p[i]) {
  240.                    printf("port open failed:%s\n", alGetErrorString(oserror()));
  241.                    exit(-1);
  242.                }
  243.               }
  244.  
  245.               /*
  246.                * Write 1000 frames of data to all the audio ports
  247.                */
  248.               while (1)
  249.               for (i =0; i < NPORTS; i++) {
  250.                alWriteBuffers(p[i], bufs[i], strides, 1000);
  251.               }
  252.           }
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268. aaaallllWWWWrrrriiiitttteeeeBBBBuuuuffffffffeeeerrrrssss((((3333ddddmmmm))))                                        aaaallllWWWWrrrriiiitttteeeeBBBBuuuuffffffffeeeerrrrssss((((3333ddddmmmm))))
  269.  
  270.  
  271.  
  272. DIAGNOSTICS
  273.      aaaallllWWWWrrrriiiitttteeeeBBBBuuuuffffffffeeeerrrrssss always returns 0.
  274.  
  275. NNNNOOOOTTTTEEEESSSS
  276.      On output, the data from all ports on the system writing to a particular
  277.      output device will be mixed together, except in the case of subcode data.
  278.      Because subcode data is treated as inherently logical information, no
  279.      amount mathematics can be applied to perform operations such as mixing.
  280.  
  281.      This function was introduced via patch to IRIX 6.3 and 6.4, and is
  282.      present by default in later OS releases.  You should ensure that the
  283.      target system will have the functionality before calling this function;
  284.      otherwise, your program will crash when you attempt to make the function
  285.      call. To determine if the feature is present, check the value of
  286.      AL_VERSION on the system resource. The parameter must be present and its
  287.      value must be at least 6.
  288.  
  289.                   pv.param = AL_VERSION;
  290.                   alGetParams(AL_SYSTEM,&pv,1);
  291.                   if (pv.sizeOut < 0 || pv.value.i < 6) {
  292.                       /* feature not present */
  293.                   }
  294.  
  295.  
  296.  
  297. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  298.      alOpenPort(3dm), alGetFillable(3dm), alGetFilled(3dm),
  299.      alSetChannels(3dm), alSetWidth(3dm), alReadFrames(3dm),
  300.      alZeroFrames(3dm), alSetConfig(3dm), alSetQueueSize(3dm),
  301.      alSetSampFmt(3dm), alSetFloatMax(3dm)
  302.  
  303.  
  304.  
  305.  
  306.  
  307.  
  308.  
  309.  
  310.  
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327.                                                                         PPPPaaaaggggeeee 5555
  328.  
  329.  
  330.  
  331.